Summary

This PR adds first-class support for Custom Token Exchange (CTE) the OAuth 2.0 Token Exchange grant (urn:ietf:params:oauth:grant-type:token-exchange, RFC 8693). This enables applications to exchange an external subject_token (for example, an M2M or partner-issued token) for Auth0 tokens.

What's Included

New AuthenticationController API

This PR introduces four new entry points:

Behavior

Login flow (loginWithCustomTokenExchange)

• Verifies the returned ID token, including:
  • Signature
  • Issuer
  • org_id / org_name (when an organization is configured)
• Uses the same verification path as the Authorization Code flow.
• Requires an ID token. If the exchange response does not include one (for example, because the openid scope was not requested), the request fails with MISSING_ID_TOKEN instead of returning an unverified success.

Utility flow (customTokenExchange)

• Does not verify the ID token, making it suitable for obtaining access tokens for downstream APIs.
• Still validates organization claims when an organization is configured.

Domain resolution

The overloads that do not take an explicit domain throw IllegalStateException when the controller is configured with a DomainResolver.

Since a DomainResolver requires an HTTP request and Custom Token Exchange may execute outside an HTTP request context, callers must use the explicit-domain overload in this configuration.

Client-side validation

Introduced CustomTokenExchangeException to validate inputs before making the request.

Validation includes:

• Rejecting empty subject tokens.
• Rejecting Bearer-prefixed subject tokens.
• Rejecting non-absolute URI token types.

Implementation

RequestProcessor.executeCustomTokenExchange(...) delegates to AuthAPI.exchangeToken(...), which is responsible for:

• Configuring the Token Exchange grant type.
• Performing client authentication (client secret or client assertion).

Files Changed

• AuthenticationController.java
  • Added the four public CTE entry points.
• TokenExchangeRequest.java (new)
  • Fluent request builder and client-side validation.
• CustomTokenExchangeException.java (new)
  • Validation exception (INVALID_TOKEN_FORMAT, INVALID_TOKEN_TYPE_URI).
• RequestProcessor.java
  • Added buildTokenExchangeRequest(...) and executeCustomTokenExchange(...).
• build.gradle
  • Updated com.auth0:auth0 from 3.5.1 to 3.10.0.

Test Plan

• ✅ AuthenticationControllerTest
  • CTE overloads
  • Login vs. utility flows
  • Explicit vs. configured domain
• ✅ RequestProcessorTest
  • Request construction
  • DomainResolver guard
  • Verification and MISSING_ID_TOKEN behavior
• ✅ TokenExchangeRequestTest
  • Client-side validation